
In this file are all the updates since the release version 3.0
If you are new to the Morfit SDK, you can ignore this file ...


The Group API
=============

//The functions below are the equivalent of Morfit_group_get\set_physics_...
//They will be useful for you only if you build some kind of World Editor (Such as Morfit World Builder)
//The functions wont show any change till we save the world and reload it in Viewer mode
//and when the chase_type is set to CHASE_PHYSICS.
//
// Return value: The rotation space (WORLD_SPACE or OBJECT_SPACE)
// through rotation_xyz[] the function returns the rotation angles
//		rotation_xyz[0] is the number of angles that the object will rotate 
//		around the X axis, each time Morfit_engine_render() is called
// see also Morfit_object_set_physics_rotation()
int     Morfit_group_get_physics_rotation(DWORD group_handle, double rotation_xyz[3]);
void    Morfit_group_set_physics_rotation(DWORD group_handle, int rotation_space ,double rotate_around_x_axis, double rotate_around_y_axis, double rotate_around_z_axis);
void    Morfit_group_get_physics_force(DWORD group_handle, double force[3]);
void    Morfit_group_set_physics_force(DWORD group_handle, double force[3]);
double  Morfit_group_get_physics_friction(DWORD group_handle);
void    Morfit_group_set_physics_friction(DWORD group_handle, double friction);
double  Morfit_group_get_physics_elasticity(DWORD group_handle);
void    Morfit_group_set_physics_elasticity(DWORD group_handle, double elasticity);
double  Morfit_group_get_physics_maxspeed(DWORD group_handle);
void	Morfit_group_set_physics_maxspeed(DWORD group_handle, double max_speed);


//This function associates a number with the group
//later (When the world is saved and load in viewer mode
//we can get this number using Morfit_object_get_control_type_number()
//Note that the function does nothing it is just a set and get mechanism. 
//The number that you give has no meaning to the Engine. 
//The meaning is as given by the application that is using the engine.
//parameters:
// num: any integer that is equal or greater than 64
// (the first 63 numbers are reserved for future use) 
void Morfit_group_set_control_number(DWORD group_handle, int num);
int Morfit_group_get_control_number(DWORD group_handle);


// Similar to Morfit_group_wrap_a_bitmap()
// The difference is that Morfit_group_wrap_a_bitmap() will
// stretch the bitmap so that the top right corner of the bitmap
// will fit to a corner of the group. This function
// will fit the corner of the bitmap the given location in the world
// locationXY_to_get_bitmap_top_left_corner[0], locationXY_to_get_bitmap_top_left_corner[1]
// This is the (X,Y) coordinate in the world that the top left corner of the bitmap will
// be associated with. 
// This way the given group might only get a portion of the bitmap.
// In the special case where locationXY_to_get_bitmap_top_left_corner, and locationXY_to_get_bitmap_bottom_right_corner
// are the bounding box of the group then this function will do the same as
// Morfit_group_wrap_a_bitmap()
// Returns OK or VR_ERROR.
int Morfit_group_wrap_a_bitmap_fixed(DWORD group_handle, DWORD bitmap_handle, int repeat_x, int repeat_y, double locationXY_to_get_bitmap_top_left_corner, double locationXY_to_get_bitmap_bottom_right_corner[2]);

// similar to Morfit_group_duplicate_tree() just that the new copy will be made of triangles only.
// Returns a handle to the new copy
 DWORD  Morfit_group_create_copy_made_of_triangles(DWORD group_to_copy) 

*** A new text. The difference is just the first line 
// Obselete .(works only in software mode
// Set the brightness of each polygon of the group according to the intensity of the light source.
// values for ambient and are in the range [0-400]
// values for light_intensity light_intensity are in the range [0-400]
// see Morfit_polygon_set_brightness() for explanation of what those values mean
// ambient is the minimum light intensity that is, if the light source has zero intensity or points
// to the opposite direction , the polygon will have the ambient intensity. This is the light that reflects
// from the surroundings.
// Examples:
// A)	direction[0]=1; direction[1]=0; direction[2]=0;
//		Morfit_group_light_group(grp, direction,20, 400) //A very strong source of light in a dark environment
//
// B)	direction[0]=1; direction[1]=1; direction[2]=0; //The direction is diagonally
//		Morfit_group_light_group(grp, direction, 100, 100) //An average source of light in an average lit environment
//
// Note that actually one can also try negative values for the ambient and the light_intensity.
// note that the formula is final_intensity= ambient + angle_between_polygon_and_light_direction* light_intensity
// where angle_between_polygon_and_light_direction is normalized to the range [0-1]
// a negative light_intensity means that our light source gives darkness instead of light ! (a great new invention !)
 void  Morfit_group_light_group(DWORD group_handle, double direction[3], double ambiant, double light_intensity);

//Remove light from the group.
//If the given group was lit using the Morfit_light API then
//this function could be used to restore the group normal appearance
//If the given group handle is NULL then light will be removed from the whole world.
//See also Morfit_object_remove_light(), Morfit_polygon_remove_light(), Morfit_light_remove_light()
void Morfit_group_remove_light(DWORD group_handle);

// Set the color of all the polygons that belong to the given group.
// rgb[0] ==red
// rgb[1]==green;
// rgb[2]==blue
//Example:
//	BYTE rgb[3]={255,0,0}; //red color
//  Morfit_group_set_color(NULL, rgb); //Set the whole world to red
void Morfit_group_set_color(DWORD group_handle, int red, int green, int blue);

//Calls Morfit_polygon_set_light() for all the polygons in the group
//For more details see Morfit_polygon_set_light()
void Morfit_group_set_light(DWORD group_handle, BYTE rgb[3]);

//Set the ambient light value to all the polygons contained in the given group
//For more details see Morfit_polygon_set_ambient()
void Morfit_group_set_ambient(DWORD group_handle, int value);

//Set the diffuse light value to all the polygons contained in the given group
//For more details see Morfit_polygon_set_diffuse()
void Morfit_group_set_diffuse(DWORD group_handle, int value);

//Set the specular light value to all the polygons contained in the given group
//For more details see Morfit_polygon_set_specular()
void Morfit_group_set_specular(DWORD group_handle, int value);

//Get the width, height and depth of the group. Please note that
//The dimensions will be returned inside the parameter "dimension"
// dimension[0] will become the depth
// dimension[1] will be the width
//dimension[2] will be the height
//the dimensions are according to the bottom and the front of the group.
//To declarea polygon as being the bottom of the group see those function
// Morfit_polygon_set_orientation()
//Returns OK or VR_ERROR;
//Example:
//		double size[3];
//		Morfit_group_get_dimensions(my_group, size);
int Morfit_group_get_dimensions(DWORD group_handle, double dimensions[3]);

*** The function is not new just the text. The olny difference is the addition of the last line (// Returns OK or VR_ERROR ).
// Similar to Morfit_group_rotate_to_match_polygon()
// with the difference that here we have an auxiliary line (going through points p1 and p2)
// To make things clearer let's say we have a square polygon_in_the_group
// and a square reference_polygon, there are four final position for the group
// so that polygon_in_the_group points to the same direction as reference_polygon.
// (each one of the four edges of one group polygon can be aligned with an edge of the
// reference polygon). Morfit_group_rotate_to_match_polygon() rotates so it will make
// the minimal rotation. This is usually what we want. So usually we will use
// Morfit_group_rotate_to_match_polygon(). We will use this function when we want
// to turn around a specific line. All the rest is exactly like in Morfit_group_rotate_to_match_polygon()
// Returns OK or VR_ERROR.
MORFIT_IMPORT int MORFIT_WINAPI Morfit_group_rotate_around_line_to_match_polygon(DWORD group_handle, DWORD polygon_in_the_group, DWORD reference_polygon, int inverse_flag, double p1[3], double p2[3]);


// Rotates the group around the given line.
// Returns OK or VR_ERROR.
int Morfit_group_rotate_around_line(DWORD group_handle, double p1[3], double p2[3], double degrees);


Animation API
==============

//Create a new animation that has the same bitmaps and timing as the given animation.
// Returns the new animation. If an error occurred, it will return NULL.
//
// Here are some ideas for using this function.
// You will need this function if you want to use the same animation but with different timing.
// For example, let say that your animation is a tree blowing in the wind. You probably
// have lots of trees and each of them use the same animation. Now if you dont want
// all the trees to move as one then you can do one of the following:
// 1) Use Morfit_polygon_set_animation_frame() to give each tree a different frame
// Or
// 2) Use this function to duplicate an animation and then to give different timing.
DWORD Morfit_animation_duplicate(DWORD animation_handle, char *new_name);


// This function can be used to replace the bitmap of a certain frame in the animation.
// bitmap_list: is one of the five constants: BITMAP_LIST_FRONT, BITMAP_LIST_FRONT_SIDED, BITMAP_LIST_SIDE, BITMAP_LIST_BACK_SIDED, BITMAP_LIST_BACK
// frame_index: 0 means the first frame. -1 has a special meaning, it means the last frame
// bitmap_handle: A handle of the bitmap that will be set for the given frame.
// See also Morfit_animation_get_bitmap()
 int  Morfit_animation_set_bitmap(DWORD animation_handle, int bitmap_list ,int frame_index, DWORD bitmap_handle);


//The return value is the name of the bitmap without the extension 
// the bitmap_name is the name+path relative to the path given in Morfit_engine_load_world()
//If a bitmap exists in the world file
//but the engine couldnt find the bitmap file than it will still return its name.
//This is used when loading a world from the Internet, at first only the world is loaded
//and then we start streaming the bitmaps. We use this function to get the bitmap file name.
//If you want to check if the bitmap is in used then use Morfit_animation_get_frame_bitmap_handle()
 char * Morfit_animation_get_frame_bitmap_name(DWORD animation_handle, int bitmap_list ,int frame_index);

//This function is very similar to Morfit_bitmap_get_transparent_index()
//For info check Morfit_bitmap_get_transparent_index()
//This function is needed only in the rare cases that some of the
//animation bitmaps could not be loaded when the world was loaded.
//For example when loading a world from the Internet, at first only the world is loaded
//and then we start streaming the bitmaps. We use this function to get the bitmap transparent index
//If you want to check if the bitmap is in used then use Morfit_animation_get_frame_bitmap_handle()
int Morfit_animation_get_frame_transparent_index(DWORD animation_handle, int bitmap_list ,int frame_index);


Card3D API
===========

The whole API was rewritten. Check it in mrft_api.h


Object API
===========
//Determines whether the object will be moved automatically according to his chase type (The movement is done each time render is called)
// yes_no_flag should be YES or NO.
//The default is YES
void Morfit_object_advance_automatically(DWORD object_handle, int yes_no_flag);


*** function already exist just a new text (I changed the name of the UNITS_PER_SECOND costant)
#define UNITS_PER_SECOND 1
#define UNITS_PER_RENDER 2
//When objects are set to go according to a specific track
//or when they move according to their physics, they have speed.
//We have two ways two work with the speed
//1-  UNITS_PER_SECOND
//	this is the default mode. It means that the object will be advanced 
//	in each render by the speed multiplied by the number of hundredths of a second
//	that have elapsed since the last render.
//	note that on slow computer the object will move with the same speed only that each render
//	the step will be bigger ...
//2-	
//	UNITS_PER_RENDER
//	Each render the object is advance by the speed, notice that we will
//	get a different speed for slow computers than on fast ones, though
//  the steps that the object is doing each render will always be equal.
//  
// The speed_units_system is always set for all the objects.
void Morfit_object_set_speed_units(int speed_units_system);


// The following functions are used for creating an hierarchy between objects and manipulating
// multiple number of objects together. For example lets say
// that we want to have a human model in our application. We should construct the model from
// several objects, the hands, the legs, the head etc ... Each object can be constructed from
// smaller objects, the hands for example could contain objects for the fingers.
// When we will move the hand we will want the finger objects to move together with the 
// hand object. We do it by setting the hand object as the father of each finger object. 
// Later we can call Morfit_object_move_including_sons(hand_object_handle) This will
// move the hand objects including all the fingers. 
// Terminology: The usage of the word TREE
//		Setting father sons relations creates a structure similar to a family tree
//
// We can call this function with father_object==NULL
// this will mean that there is no father for this object.
// Returns OK or VR_ERROR.
// If the function fails it means that we tried to make a loop in hierarchy of the objects
// (for example setting object B as the father of object A and then setting object A as the father of B)
int  Morfit_object_set_father_object(DWORD object_handle, DWORD father_object);
DWORD Morfit_object_get_father_object(DWORD object_handle);

// returns YES or NO. 
// A NULL object_handle means the whole world
// Note that if groupA_handle==groupB_handle it will return YES
// If groupB_handle==NULL it will always return YES.
 int  Morfit_object_is_objectA_included_in_objectB(DWORD objectA_handle, DWORD objectB_handle);

//Returns the first son of the given object. This function together with Morfit_object_get_next_son()
// create an easy way for going over all the descendants (son, grandchild etc ...) of an object.
// for example: 
//	for(son=Morfit_object_get_first_son(car_object); son!=NULL; son=Morfit_object_get_next_son(son)) {
//		//your code here ....
//	}
// Note that if you just want to go over all the direct sons (no grandchildren ...) you should
// use Morfit_object_get_first_direct_son() and Morfit_object_get_next_direct_son()
 DWORD  Morfit_object_get_first_son(DWORD object_handle);
 DWORD  Morfit_object_get_next_son(DWORD object_handle, DWORD son_handle);

//Returns the first immediate son of the given object. This function together with Morfit_object_get_next_direct_son()
// create an easy way for going over all the direct son (the close family) of an object.
// for example: 
//	for(son=Morfit_object_get_first_direct_son(car_object); son!=NULL; son=Morfit_object_get_next_direct_son(son)) {
//		//your code here ....
//	}
// Note that if you want to go over all the descendants (including grandchildren ...) you should
// use Morfit_object_get_first_son() and Morfit_object_get_next_son()
 DWORD  Morfit_object_get_first_direct_son(DWORD object_handle);
 DWORD  Morfit_object_get_next_direct_son(DWORD object_handle, DWORD son_handle);


// Advance the object (move relative) including all of its descendants
// space_flag could be WORLD_SPACE or OBJECT_SPACE or CAMERA_SPACE
// space_flag determines if the step is according to the objects
// coordinate system or the world coordinate  system etc ...
// for example if space_flag==OBJECT_SPACE and step==(-1,0,0)
// This means that the object will advance forward (If it is a car than
// forward is the direction of the front window).
// Try both option and see what happens.
void Morfit_object_move_including_sons(DWORD top_object_handle, int space_flag, double x, double y, double z)



// Calculates the center of the collection of objects defined by the given object and all of its descendants
// The result is saved in the center argument.
// ("tree" means the whole family tree of the object)
//Return value: returns the number of objects in the tree
 int  Morfit_object_get_center_of_tree(DWORD top_object_handle, double center[3]);

#define CENTER_OF_TOP_OBJECT 1
#define CENTER_OF_TREE 2
#define CENTER_AS_GIVEN 3
// Move the object and all its descendants to a new location. center_flag can be one of the two: CENTER_OF_TOP_OBJECT or CENTER_OF_TREE
// If CENTER_OF_TREE is given then after calling this function the center of the tree will be in the given new location.
// If CENTER_OF_TOP_OBJECT then after calling this function the center of the top object will be in the given new location.
 void  Morfit_object_set_location_of_tree(DWORD top_object_handle, double new_location[3], int center_flag);

//The object and all its descendants will be rotated according to the given arguments:
// degrees: The number of degrees to rotate.
// axis: this could be 1 or 2 or 3. Give one for rotating around the X axis. 2 for rotating around the Y axis and 3 for the Z axis
// space_flag: OBJECT_SPACE or  WORLD_SPACE. If we have chosen for example to rotate around the X axis
//								this flag determines whether it is the X axis of the object or the X axis of the world.
// center_flag: Could be one of the three, CENTER_OF_TOP_OBJECT, CENTER_OF_TREE, CENTER_AS_GIVEN.
//				This flag determines the center of rotation.
// center: this argument is only relevant if the center_flag is CENTER_AS_GIVEN. In this case the point given by this
//				argument will define the center of rotation.
 void  Morfit_object_rotate_including_sons(DWORD top_object_handle, double degrees, int axis, int space_flag, int center_flag, double center[3]);

//Remove light from the given object.
//If the given object was lit using the Morfit_light API then
//this function could be used to restore the object normal appearance
//See also Morfit_group_remove_light(), Morfit_polygon_remove_light(), Morfit_light_remove_light()
void Morfit_object_remove_light(DWORD object_handle)

//Sets the given bitmap to all the polygons of the object. The bitmap serves as a skin.
//Returns OK or VR_ERROR 
void Morfit_object_set_bitmap(DWORD object_handle, DWORD bitmap_handle);

//Creates an empty object and returns its handle.
//The object is automatically added to the engine
__declspec(dllexport) DWORD MORFIT_WINAPI Morfit_object_create(char *name);

//Similar to Morfit_engine_add_world() the difference is that
//the added world file is added as a dynamic object.
//Example:
// girl=Morfit_object_create_from_file("people\\girl.md2");
__declspec(dllexport) DWORD MORFIT_WINAPI Morfit_object_create_from_file(char *file_name);


//Returns the object 3D_animation or NULL if it doesnt have any 3D animation
// Example:
// my_obj=Morfit_object_create_from_file("woman.md2"); //The md2 files contain a 3D animation. The 3D animation is automatically loaded to the engine
// my_3danim=Morfit_object_get_3D_animation();
// walk_sequence=Morfit_3D_sequence_get_using_name(my_3danim,"walk");
// standing_sequence=Morfit_3D_sequence_get_using_name(my_3danim,"stand");
// undressing_sequence=Morfit_3D_sequence_get_using_name(my_3danim,"undress");
// if(key_1_is_pressed) Morfit_object_set_3D_sequence(my_obj,walk_sequence); 
// if(key_2_is_pressed) Morfit_object_set_3D_sequence(my_obj,undressing_sequence); 
// and so on ...
__declspec(dllexport) DWORD MORFIT_WINAPI Morfit_object_get_3D_animation(DWORD object_handle);
__declspec(dllexport) int MORFIT_WINAPI Morfit_object_set_3D_animation(DWORD object_handle, DWORD animation3d_handle);
__declspec(dllexport) void MORFIT_WINAPI Morfit_object_set_3D_sequence(DWORD object_handle, DWORD sequence3d_handle);
__declspec(dllexport) DWORD MORFIT_WINAPI Morfit_object_get_3D_sequence(DWORD object_handle);


//new_sequence3d_handle is the handle to the sequence that we want to play when the current sequence
//reached its last frame.
__declspec(dllexport) void MORFIT_WINAPI Morfit_object_replace_3D_sequence_when_finished(DWORD object_handle, DWORD new_sequence3d_handle, int transition_period);

//Scale the object.
//Example:
// double scale[3]={1,2,3};
// Morfit_object_scale(my_object, scale);
void Morfit_object_set_scale(DWORD object_handle, double scale[3]);

//Returns the scaling factor. The default is 1,1,1
// After calling this function
// scale[0] will hold the X scaling factor
// scale[1] will hold the Y scaling factor
// scale[2] will hold the Z scaling factor
// Example:
//		double scale[3];
//		Morfit_object_get_scale(my_object,scale);
void Morfit_object_get_scale(DWORD object_handle, double scale[3]);



//Returns the handle to the group that represents this object.
DWORD Morfit_object_get_group_handle(DWORD object_handle);

//Calls Morfit_polygon_set_light() for all the polygons in the object
//For more details see Morfit_polygon_set_light()
void Morfit_object_set_light(DWORD object_handle, BYTE rgb[3]);

//Adds a polygon to the object.
//Please note that the points of the polygon should be in OBJECT_SPACE
//(for example 0,0,0 is the center of the object and not the center of the world)
// Adding polygons that are defined in the object space is very easy because we don't
//have to take care whether the object has moved or turned around. For example
//if we have an airplane that is flying then in object space the coordinates
//of the points that define a polygon on the airplane wing will always stay the same
//no matter how many maneuvers the airplane did.
//One can use the function Morfit_object_convert_point_to_object_space()
//If the points of the polygon are only known in world space. 
//Returns OK or VR_ERROR
//If the return value is VR_ERROR it is probably because that the polygon is not valid.
//(for example it has only two points. 4 points not on the same plane. not convex,
//bitmap coordination are not valid etc ...see the morfit.log to catch the error)
int Morfit_object_add_polygon(DWORD object_handle, DWORD polygon_handle);



Engine API
============

This function was deleted:
	Morfit_engine_activate_DirectX(); 


//When rendering takes more than the specified time then the rendering function will exit automatically
//This is very useful when rendering indoor worlds. The engine renders front to back
// so it is usually enough to stop rendering after finishing with the current room.
// Try playing with different values and see the result.
//The default is 1000000 (which is about 17 minutes which is similar to "take all the time in the world to finish every rendering")
//Typical values would be 200,100,50
// Note that this function is only relevant in Viewer Mode (Viewer Mode is the the default mode)
//Example: Morfit_engine_set_maximum_rendering_time(100); //Set minimum frames per seconds to 10
void  Morfit_engine_set_maximum_rendering_time(int max_duration_in_mili_seconds);
int  Morfit_engine_get_maximum_rendering_time(void);

//Sets a minimum time for each render. If Morfit_engine_render() take less time
//than the specified time then the engine will wait (Doing Sleep() ) till it reaches the given
// duration.
// Why should you use this function ? Sometimes when you get to the end of your world
// The engine has only few polygons to render in this case it can get to 1000 frames per seconds and more !!!
// If you are moving a car by X units every render then your car is going to become
// a rocket when you reach the end of the world ...
// The default is 2. This permits a maximum of 500 frames per seconds
// Note also the function Morfit_engine_get_computer_speed_factor()
//Example: Morfit_engine_set_minimum_rendering_time(0);
void  Morfit_engine_set_minimum_rendering_time(int min_duration_in_mili_seconds);
int  Morfit_engine_get_minimum_rendering_time(void);


//Controls the amount of CPU time that the rendering process gets.
//Usually you would like to have the fastest graphics possible
//though sometime when a few application are working in conjunction
//there is need to release some CPU time for the benefit of the others.
// parameters:
//		thread_priority: (For more details please see the win32 function SetThreadPriority() )
//
//			THREAD_PRIORITY_ABOVE_NORMAL 
//				Indicates 1 point above normal priority for the priority class. 
//			THREAD_PRIORITY_BELOW_NORMAL Indicates 
//				1 point below normal priority for the priority class. 
//			THREAD_PRIORITY_HIGHEST 
//				Indicates 2 points above normal priority for the priority class. 
//			THREAD_PRIORITY_IDLE 
//				Indicates a base priority level of 1 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base priority level of 16 for REALTIME_PRIORITY_CLASS processes. 
//			THREAD_PRIORITY_LOWEST 
//				Indicates 2 points below normal priority for the priority class. 
//			THREAD_PRIORITY_NORMAL 
//				Indicates normal priority for the priority class. 
//			THREAD_PRIORITY_TIME_CRITICAL 
//				Indicates a base priority level of 15 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base priority level of 31 for REALTIME_PRIORITY_CLASS processes. 
//
//		Class priorities: ( For more details please see the win32 function SetPriorityClass() )
//
//			HIGH_PRIORITY_CLASS 
//				Specify this class for a process that performs time-critical tasks that must be executed immediately. The threads of the process preempt the threads of normal or idle priority class processes. An example is the Task List, which must respond quickly when called by the user, regardless of the load on the operating system. Use extreme care when using the high-priority class, because a high-priority class application can use nearly all available CPU time. 
//			IDLE_PRIORITY_CLASS 
//				Specify this class for a process whose threads run only when the system is idle. The threads of the process are preempted by the threads of any process running in a higher priority class. An example is a screen saver. The idle-priority class is inherited by child processes. 
//			NORMAL_PRIORITY_CLASS 
//				Specify this class for a process with no special scheduling needs. 
//			REALTIME_PRIORITY_CLASS 
//				Specify this class for a process that has the highest possible priority. The threads of the process preempt the threads of all other processes, including operating system processes performing important tasks. For example, a real-time process that executes for more than a very brief interval can cause disk caches not to flush or cause the mouse to be unresponsive. 
//Examples:
// A)
//		Setting High priority (The default)
//		Morfit_engine_set_thread_priority(THREAD_PRIORITY_HIGHEST, HIGH_PRIORITY_CLASS);
//
// B)
//		Setting the fastest rendering possible
//		Morfit_engine_set_thread_priority(THREAD_PRIORITY_TIME_CRITICAL, REALTIME_PRIORITY_CLASS);
//
// For more details please see the win32 functions SetPriorityClass() and SetThreadPriority()
void Morfit_engine_set_thread_priority(int thread_priority, DWORD class_priority);


//This function must be called when before your program exits.
//Not calling this function at the end of your program might 
//cause your program not to exit cleanly (Crashing at the end)
void Morfit_engine_close(void);


//This function is very important. It allows painting and writing over the rendered image
//The function is exactly like Morfit_engine_render() only that it doesnt write the
//rendered image into the screen, instead the image is left on the device context ( dc )
//If you dont know what is a Device Context then dont bother about it
//just think of it as a handle that many WIN32 graphic functions get.
//The beauty of this technique that one can use all the many Windows function
// (GDI functions)  
// After finishing painting on top of the rendered image 
// use Morfit_engine_bitblt() to draw the finished image on the
// window
//
//Here is a sample how to use Morfit_engine_render_on_dc()
//
//		HDC dc=Morfit_engine_render_on_dc(NULL,camera);	
//
//	    //paints a circle on the device context. 
//		//Note that ELlipse() is a Windows function (WIN32 API)
//		//Look in you compiler help for information about that function.
//		//There are many other function that you can use for writing tect changing
//      //colors, changing the fill pattern etc ...
//		Ellipse(dc, 100,100,200,200);
//		//paint another circle
//		Ellipse(dc, 220,220,320,320);
//		
//		//Get the picture on the screen. Without calling this function you
//      //wont see anything.
//		Morfit_engine_bitblt();
//
//
// For drawing a wire frame lines around polygons note the function Morfit_engine_3D_edge_to_2D()
//
HDC Morfit_engine_render_on_dc(HWND hwnd, DWORD camera_handle);

// Redraw on the window the last rendered image
// Usually used together with Morfit_engine_render_on_dc()
// Note that this function also releases the dc the was obtained
// when calling Morfit_engine_render_on_dc() this means that
// all the function that use the returned dc (from dc=Morfit_engine_render_on_dc() )
// must be called before calling Morfit_engine_copy_image_from_dc_to_screen().
// 
// Note that this function is completely identical to Morfit_engine_bitblt()
//
//See Morfit_engine_render_on_dc() for more information.
//
void  Morfit_engine_copy_image_from_dc_to_screen(void);

//Returns Morfit's logo
HBITMAP Morfit_engine_get_logo(void);


*** It is not a new function just a new text ...
// gets a two dimensional point=> (x,y) is a point in the rendered window
// usually we get this point from the events like OnLButtonDown()
// and retrieves the corresponding three dimensional point
// in the virtual space. Note that if we give a 2D point where there is no 
// polygon rendered we will get VR_ERROR because the point
// in 3D is in infinity ... in that case the 3d point retrieved (result[] )
// will hold a point in that direction that is one million units away
// from the camera.
int  Morfit_engine_2D_point_to_3D(int x, int y, double result[3], DWORD *selected_object_handle, DWORD *selected_polygon_handle);


*** Added after August
//Show the frames per second rate at the top left of the rendered window.
//by default it is activated. This function is only relevant in hardware rendering (see Morfit_3D_card_use() )
//Example:
//Morfit_engine_show_frames_per_second_rate(NO); 
void Morfit_engine_show_frames_per_second_rate(int YES_or_NO);


*** The function isn't new just the text
//This function must be called before your program exits.
//Not calling this function at the end of your program might 
//cause your program not to exit cleanly (Crashing at the end)
//This function should not be called from inside a destructor
MORFIT_IMPORT void MORFIT_WINAPI Morfit_engine_close(void);



Polygon API
==============
//Checks whether the given line segment intersect the given polygon.
//Returns YES if there is an intersection. Returns NO otherwise.
//The line segment is define by two points: double P1[3] and double P2[3]
//If there is an intersection the intersection point is saved within double intersection[3]
// Wont work in VIEWER_MODE with polygons that belong to a dynamic object (See the Morfit_object API)
int Morfit_polygon_check_intersection_with_line_segment(DWORD polygon_handle, double P1[3], double P2[3], double intersection[3]);


//Checks whether the two given polygons intersect each other.
//Returns YES if there is an intersection. Returns NO otherwise.
//If there is an intersection the intersection point is saved within double intersection[3]
// Wont work in VIEWER_MODE with polygons that belong to a dynamic object (See the Morfit_object API)
int Morfit_polygon_check_intersection_with_another_polygon(DWORD polygon1, DWORD polygon2, double intersection[3]);

//Exactly like Morfit_group_wrap_a_bitmap_fixed(0 but just for one polygon.
// See also Morfit_group_wrap_a_bitmap()
int Morfit_polygon_wrap_a_bitmap_fixed(DWORD polygon_handle, DWORD bitmap_handle, int repeat_x, int repeat_y, double locationXY_to_get_bitmap_top_left_corner[2], double locationXY_to_get_bitmap_bottom_right_corner[2]);


*** It is not a new function just a new text ...
// If the return is NULL then no bitmap is associated with the polygon
//the return value is The name of the bitmap without the extention 
// the bitmap_name is the name+path relative to the path given in Morfit_engine_load_world()
//If a bitmap exists in the world file
//but the engine couldnt find the bitmap file than it will still return its name.
//This is used when loading a world from the Internet, at first only the world is loaded
//and then we start streaming the bitmaps. We use this function to get the bitmap file name.
//If you want to check if the bitmap is in used then use Morfit_polygon_get_bitmap_handle()
// example:
// the executable path is d:\projects\test
// the bitmap path == d:\projects\test\bitmaps\animal\dog\boxer.bmp
// the bitmap path given in Morfit_engine_load_world() == "bitmaps"
// the return string here will be == "animal\dog\boxer"
char * MORFIT_stdcall Morfit_polygon_get_bitmap_name(DWORD polygon_handle) ;


*** just a new text. The difference is the first two lines.
// Assuming that there is an animation associated with the given polygon
// then this function makes it possible to jump to a specific frame. 
// If animation_frame==-1 then the last frame will be chosen.
// If the given animation_frame is bigger than the last frame then the last frame will be chosen.
// The first frame is numbered as 0
void Morfit_polygon_set_animation_frame(DWORD polygon_handle, int animation_frame);

//Set the light values of each vertex directly
//Usually it is easier to use the light API to set the vertices
//color.
//The function calls Morfit_point_set_rgb() for all the points of the given polygon
//Note that this function will only work in hardware rendering mode
//One can try playing with this function to create nice effects.
//For example fading the polygon to the color of the background.
//See also Morfit_point_set_rgb()
void Morfit_polygon_set_light(DWORD polygon_handle, BYTE rgb[3]);

*** The function isn't new just the text
// The given value should describe the percentage of fog increment per 1000 units
// Give 0 to cancel fog for a particular polygon.
// This might come handy when working with translucent polygons.
// Returns OK, VR_ERROR
int  Morfit_polygon_set_light_diminution(DWORD polygon_handle, double value); 
double Morfit_polygon_get_light_diminution(DWORD polygon_handle); 

//----------------------------------------------------------------------------
//=== Polygon function that has to do with light. See also the Light API =====
//----------------------------------------------------------------------------

// There are four properties that influence how light effects polygons, these are ambient, diffuse specular and specular_shining.
// Every defined light that is activated (see the light API) is combined internally of
// three types of lights (ambient, diffuse and specular)
// By using these functions one can modify how a surface react with each type of light.
// Different materials react differently For example
// materials that tend to reflect light better (metals, marble etc ...)
// will have higher values of the specular property. 
// The value given should be a positive number
// The default value is 86. Typical values are between 0 to 500
// Feel free to play with those values till you get the desired effect
// Here is some more info about the light properties
// Specular:
// The specular property defines for a surface how close it is to an ideal reflecting surface
// A mirror for example is a perfect reflecting surface. 
// Different materials have different values .For example
// materials that tend to reflect light better (metals, marble etc ...)
// will have higher values of the specular property.
// Diffuse:
// Diffuse light comes from a particular direction but is reflected evenly of the surface
// Dull surfaces like solid matte plastic exhibit what is called diffuse reflection
// Ambient:
// Ambient light is light that doesn't come from any particular direction
// Objects illuminated by ambient light are evenly lit on all surfaces.
void  Morfit_polygon_set_ambient(DWORD polygon_handle, int value);
int  Morfit_polygon_get_ambient(DWORD polygon_handle);
void  Morfit_polygon_set_diffuse(DWORD polygon_handle, int value);
int  Morfit_polygon_get_diffuse(DWORD polygon_handle);
void  Morfit_polygon_set_specular(DWORD polygon_handle, int value);
int  Morfit_polygon_get_specular(DWORD polygon_handle);
// The shining property influences only the specular light
// The default is 1. Typical values are between 0 to 10
// The lower this value is the bigger the light spot created from the specular lighting will be.
void  Morfit_polygon_set_specular_shining(DWORD polygon_handle, BYTE value);
// The shining property influences only the specular light
// The default is 1. Typical values are between 0 to 10
// The lower this value is the bigger the light spot created from the specular lighting will be.
BYTE  Morfit_polygon_get_specular_shining(DWORD polygon_handle);

//Remove light from the polygon.
//If the given polygon was lit using the Morfit_light API then
//this function could be used to restore the polygon normal appearance
//See also Morfit_object_remove_light(), Morfit_group_remove_light(), Morfit_light_remove_light()
void Morfit_polygon_remove_light(DWORD polygon_handle);

// Ignore this polygon for collision detection 
// purposes. This means that when Morfit_object_is_movement_possible()
// will be called ( or Morfit_engine_is_movement_possible() ) they would never get collision with
// this polygon. This function is useful for polygons representing clouds, smoke, curtains ,grass etc ...
// The default is that all the polygons are collisional
// see also Morfit_polygon_make_collisional() and Morfit_polygon_is_collisional()
void  Morfit_polygon_make_non_collisional(DWORD polygon_handle);

//This is the default. see also Morfit_polygon_make_non_collisional() and Morfit_polygon_is_collisional()
void  Morfit_polygon_make_collisional(DWORD polygon_handle);

//Return YES or NO. see also Morfit_polygon_make_collisional() and Morfit_polygon_make_non_collisional()
int  Morfit_polygon_is_collisional(DWORD polygon_handle);


====================================================
============ P O I N T    A P I ====================
====================================================

// This function will return the rgb values of the point
// Red will be returned in rgb[0] 
// Green will be returned in rgb[1] 
// Blue will be returned in rgb[2] 
// Note that these values are only relevant with hardware rendering.
// The default is (255,255,255).
// By changing the rgb value we can create light and atmospheric effects.
//
// How the rgb values are combined with the texture color and the polygon color
// to form the final color of each pixel:
// ----------------------------------------------------------------------------
// The final color of a pixel in a polygon is
// an outcome of the rgb values of the vertexes and the polygon texture or color
// The rgb of the vertexes is interpolated for every pixel of the polygon
// The interpolated value is multiplied by the texture color of every pixel.
// (If there is no texture then it is multiplied by the color of the polygon)
// Before multiplying the rgb is converted to a 0 till 1 scale.
// Example: Lets say we have a red polygon with its color set to (240,10,10)
// Lets assume that this is a triangle and that the rgb value of the vertexes is 
// (255,0,0 ) , (0,255,0) , (0,0,255). If we take a point in the center of the polygon
// then the interpolated value from the three vertexes will be something like (83,83,83)
// when 83 is converted from 0-255 scale to 0-1 scale we get that the interpolated value
// is (0.33, 0.33, 0.33). Now let multiply this value with the color of the polygon
// we get: (0.33, 0.33, 0.33) * (240, 10, 10) == (80, 3, 3)
// The result pixel will be (80,3,3)
//
// Special cases.
// --------------
// 1) If the RGB value of all the vertexes is (255,255,255)
// Then it wont have any effect since in scale of [0-1]
// it will become (1,1,1) and then the multiplication wont change
// the value of the pixel
// 2) If the polygon has no bitmap and its color is white (255,255,255)
// In this case the rgb values of the vertexes determine alone the color
// of the final pixel. This is also known as Gouraud shading
//
void Morfit_point_get_rgb(DWORD point_handle, BYTE rgb[3]);


// This function will set the rgb values of the point
// Red should be given in rgb[0] 
// Green should be given in rgb[1] 
// Blue should be given in rgb[2] 
// Note that these values are only relevant with hardware rendering.
// By changing the rgb value we can create light and atmospheric effects.
// The light API is based on this function. Usually one would
// use the light API function though sometimes it nice to have the direct control
// for creating special effects.
//
// How the rgb values are combined with the texture color and the polygon color
// to form the final color of each pixel:
// ----------------------------------------------------------------------------
// The final color of a pixel in a polygon is
// an outcome of the rgb values of the vertexes and the polygon texture or color
// The rgb of the vertexes is interpolated for every pixel of the polygon
// The interpolated value is multiplied by the texture color of every pixel.
// (If there is no texture then it is multiplied by the color of the polygon)
// Before multiplying the rgb is converted to a 0 till 1 scale.
// Example: Lets say we have a red polygon with its color set to (240,10,10)
// Lets assume that this is a triangle and that the rgb value of the vertexes is 
// (255,0,0 ) , (0,255,0) , (0,0,255). If we take a point in the center of the polygon
// then the interpolated value from the three vertexes will be something like (83,83,83)
// when 83 is converted from 0-255 scale to 0-1 scale we get that the interpolated value
// is (0.33, 0.33, 0.33). Now let multiply this value with the color of the polygon
// we get: (0.33, 0.33, 0.33) * (240, 10, 10) == (80, 3, 3)
// The result pixel will be (80,3,3)
//
// Special cases.
// --------------
// 1) If the RGB value of all the vertexes is (255,255,255)
// Then it wont have any effect since in scale of [0-1]
// it will become (1,1,1) and then the multiplication wont change
// the value of the pixel
// 2) If the polygon has a bitmap and its color is white (255,255,255)
// In this case the rgb values of the vertexes determine alone the color
// of the final pixel. This is also known as Gouraud shading
//
void Morfit_point_set_rgb(DWORD point_handle, DWORD father_polygon, BYTE rgb[3]);

*** The function is not new, just a new text
// Gets the point (x,y,z) coordinate.
//Please note that if the point belongs to a dynamic object then the returned (x,y,z) will be in OBJECT_SPACE.
// To get the point in WORLD_SPACE you should write the following code:
//
// double xyz[3];
// Morfit_point_get_xyz(my_point, xyz);
// double xyz_world_space
// Morfit_object_convert_point_to_world_space(my_object, xyz, xyz_world_space);
void Morfit_point_get_xyz(DWORD point_handle, double xyz[3]); 

*** The function is not new, just a new text
// Sets the point (x,y,z) coordinate.
// After changing the points of a polygon dont forget to call Morfit_polygon_is_valid()
// This call is needed for recalculating internal data of the polygon (such as the polygon's normal)
// Please note that if the point belongs to a dynamic object then the (x,y,z) should be in OBJECT_SPACE.
// To get a x,y,z coorinate in OBJECT_SPACE you should write the following code:
//
// double xyz[3];
// xyz[0]=100; xyz[1]=200; xyz[2]=300;  //setting the coordinate (world space)
// double xyz_object_space[3]
// Morfit_object_convert_point_to_object_space(my_object, xyz, xyz_object_space);
// Morfit_point_set_xyz(my_point, xyz);
void Morfit_point_set_xyz(DWORD point_handle, double xyz[3]); 



Background API
=================

//Returns the background handle that is currently in use
DWORD Morfit_background_get_current_background()

// Returns the name of the bitmap. Note the difference between calling Morfit_background_get_bitmap()
//and then getting the bitmap name using Morfit_bitmap_get_name()
// The difference is that here we will get the name even if the bitmap was not loaded yet.
// For example when our world is on the Internet then we first download the world and only then 
// the bitmaps are downloaded. If we call this function we would still get the name even though the bitmap wasn't
// loaded to the engine yet. If you didnt understand this explanation then relax, it is not so important.
char * Morfit_background_get_bitmap_name(DWORD background_handle); 


==================
*** Camera API ***
==================

*** The function is not new just the text.
//Sets the axis system of the camera explicitly.
// X,Y,Z are three unit vectors that defines the view space. -X is the direction
// of viewing.
//The function works exactly like Morfit_object_set_axis_system()
//See Morfit_object_set_axis_system() for more information.
// Returns OK or VR_ERROR
MORFIT_IMPORT int MORFIT_WINAPI  Morfit_camera_set_axis_system(DWORD camera_handle, double X[3], double Y[3], double Z[3]);

*** The function is not new just the text.
//Gets the axis system of the camera..
// X,Y,Z are three unit vectors that defines the view space. -X is the direction
// of viewing.
// See also Morfit_camera_set_axis_system()
MORFIT_IMPORT void MORFIT_WINAPI Morfit_camera_get_axis_system(DWORD camera_handle, double X[3], double Y[3], double Z[3]);


==================
*** Bitmap API ***
==================

*** The function is not new just the text. The only change is the given example
// Returns a handle to a previously  loaded bitmap (using the file name)
// If the return value is NULL it means 
// that no bitmap with the given name and the given transparent index was loaded to the engine.
//Think of the transparent_index as part of the name 
//there could be several bitmaps with the same name but each can have a different
//transparent index. Note that the engine keeps a separate copy for each transparent index
//Example:
// Morfit_bitmap_get_handle("bitmaps\\people\\man12.bmp",-1);
__declspec(dllexport) DWORD MORFIT_WINAPI Morfit_bitmap_get_handle(char *file_name, int transparent_index);


=====================
*** Utilities API ***
=====================

//Loads a file into memory.
//returns a pointer to the allocated memory and the size of the file
//If the file could not be loaded a NULL is returned.
//This file can be also treated as a string (there will always be a terminating NULL ...).
//Example:
//		int file_size;
//		char *buff=Morfit_utilities_file_to_memory("help.txt", &file_size);
//		MessageBox(NULL,buff,"Help", MB_OK);
//		Morfit_utilities_free_file_memory(buff);
BYTE *Morfit_utilities_file_to_memory(char *file_name, int *file_size);

//Used together with Morfit_utilities_file_to_memory() to free memory
//that we don't need any more.
//note that "void *mem_ptr" is a pointer to void which means
//that it will accept any type of pointer.
void Morfit_utilities_free_file_memory(void *mem_ptr);


// This is a very useful function.
// It can be used for pasting 2D bitmaps on the rendered image
// For example an image denoting the health condition of the player
// or the existence of ammunition
// The function copies a bitmap on the given device context.
// Use Morfit_utilities_load_bitmap_from_file() to get a handle to the bitmap (HBITMAP)
// Use Morfit_engine_render_on_dc() to get the device context handle (HDC hdc)
//
// Parameters:
//
// hdc:				a handle to the device context. usually you would obtain this
//					handle from calling hdc=Morfit_engine_render_on_dc()
//		
// hbm:				a HBITMAP handle of the bitmap. you can use 
//					Morfit_utilities_load_bitmap_from_file() to get
//					the handle.
//
// x,y:				the coordinate where the bitmap should be placed
//
// bm_stretch_width,
// bm_stretch_height:	Using these params you can stretch the bitmap
//						If you dont want to stretch the bitmap give -1
//						
//
// Examples:
//
// A) 
//	//Copy the bitmap to the top left corner of the window
//	Morfit_utilities_copy_bitmap_on_dc(hdc, hbm, 0,0, -1,-1);
//
// B) 
//	//Copy the bitmap to the top left corner of the window
//	//The bitmap will be stretched to a 100x100 square size (size in pixels)
//	Morfit_utilities_copy_bitmap_on_dc(hdc, hbm, 0,0, 100, 100);
//
void Morfit_utilities_copy_bitmap_on_dc(HDC hdc, HBITMAP hbm, int x, int y, int bm_stretch_width, int bm_stretch_height);


====================
*** The Math API ***
====================

//Returns the scalar product between two vectors.
//The return value is the length of the first vector multiply by
//the length of the second multiplied by the cosine of the angle between the
//two vectors.
//In a formula way it looks like that:
// return value= scalar_product= |vec1|*|vec2|*cos(alpha) . Alpha is the angle between the vectors
//For more information about scalar products see your math book (look for Linear Algebra and vectors)
double Morfit_math_product(double vec1[3], double vec2[3]);

//Returns the cross product between vec1 and vec2.
//The result is returned in the argument "result"
//The returned vector is a vector that is perpendicular both to vec1 and vec2
//The length of the returned vector is equal to
//The length of vec1 multiplied by the length of vec2 multiplied by
//the sinus of the angle between the two vectors.
//For more information about scalar products see your math book (look for Linear Algebra and vectors)
void Morfit_math_cross(double vec1[3], double vec2[3], double result[3]);


//returns OK or VR_ERROR
//normalize the vector. This means make it a unit vector.
//In other words the direction of the vector will stay the same
//but its length will become one
//example:
//		double vec[3]={6,8,0} //length==10
//		Morfit_math_normalize_vec(vec);
//		//Now the vec will be equal to { 0.6, 0.8, 0} (length==1)
int Morfit_math_normalize_vector(double vec[3]);


//Returns the length (magnitude) of the vector
double Morfit_math_get_vector_length(double vec[3]);


============================
T h e   L I G H T     A P I
============================

The whole light API is new !!!

//This API deals with making light. It supports dynamic colored Gouraud shading light !
// Please also notice this powerful function: Morfit_engine_create_shadow()
// Morfit_engine_create_shadow() uses projection method techniques for creating light
// while the light API is using Gouraud shading technique. Both methods
// could be mixed together to create great effects.
// Please also note that Gouraud shading is using vertex lighting.
// This means that the effects will be much better if there are more vertexes (that means more polygons)


//-----------------------------------------------------------//
//========= T H E   3 D _ A N I M A T I O N   A P I =========//
//-----------------------------------------------------------//

//This whole API is new
//This API deals with 3D model animation (mesh morphing)
The whole API is new

3D_sequence API
---------------
The whole API is new


Sound A P I
-------------
The whole sound A P I is new.
Note that if you intend to use the sound API within a commercial application
you must purchase a license from Morfit. If in doubt email us to support@morfit.com

